Inside Macintosh: 3D Graphics Programming With QuickDraw 3D /

Chapter 12 - Draw Context Objects

Using Draw Context Objects

QuickDraw 3D supplies routines that you can use to create and configure draw context objects. This section describes how to accomplish these tasks.

Creating and Configuring a Draw Context

You create a draw context object by calling a constructor function such as Q3MacDrawContext_New or Q3PixMapDrawContext_New. These functions
take as a parameter a pointer to a data structure that contains information about the draw context you want to create. For example, you pass the Q3MacDrawContext_New function a pointer to a structure of type TQ3MacDrawContextData, defined as follows:

typedef struct TQ3MacDrawContextData {
   TQ3DrawContextData                  drawContextData;
   CWindowPtr                          window;
   TQ3MacDrawContext2DLibrary          library;
   gxViewPort                          viewPort;
   CGrafPtr                            grafPort;
} TQ3MacDrawContextData;

The first field is just a draw context data structure that contains basic information about the draw context (see page 12-4). The remaining fields contain specific information about the Macintosh window and 2D graphics library associated with the draw context.

See Listing 1-7 on page 1-26 for a sample routine that creates a Macintosh
draw context.

Using Double Buffering

In general, when drawing to a screen or other device visible by the user, you'll want to use QuickDraw 3D's double buffering capability to reduce the amount of flicker that occurs when the image on the screen is updated. You enable double buffering by calling Q3DrawContext_SetDoubleBufferState or by setting the doubleBufferState field of a draw context data structure to kQ3True before calling the draw context constructor method.

Note

In general, QuickDraw 3D will take advantage of any double buffering capabilities available on the target window system.

When double buffering is active for a draw context, the draw context is associated with two buffers, the front buffer and the back buffer. The front buffer is the area of memory that is being displayed on the screen. The back buffer is some other area of memory that has the same size as the front buffer.

When double buffering is active, all drawing (as performed by routines such as Q3Group_Submit in a rendering loop) is done into the back buffer, and the front buffer is updated only after the call to Q3View_EndRendering on the final pass through your rendering loop. Some renderers (especially those that rely on hardware accelerators) may return control to your application before the image on the screen has been updated. You can call the Q3Renderer_Sync function to block execution until the renderer is done drawing in the screen's draw context. You might want to do this if you intend to grab the image on the screen or if you intend to allow the user to pick objects displayed on the screen. See the chapter "Renderer Objects" for complete information about calling Q3Renderer_Sync.